Linux Cubed Series 2: Applications

home *** CD-ROM | disk | FTP | other *** search

/ Linux Cubed Series 2: Applications / Linux Cubed Series 2 - Applications.iso / editors / emacs / xemacs / xemacs-1.006 / xemacs-1 / lib / xemacs-19.13 / info / lispref.info-24 < prev next >

Wrap

GNU Info File | 1995-09-01 | 49.5 KB | 1,253 lines

This is Info file ../../info/lispref.info, produced by Makeinfo-1.63 from the input file lispref.texi. Edition History: GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994 XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995 GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp Programmer's Manual (for 19.13) Third Edition, July 1995 Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc. Copyright (C) 1995 Amdahl Corporation. Copyright (C) 1995 Ben Wing. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Foundation. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the section entitled "GNU General Public License" is included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that the section entitled "GNU General Public License" may be included in a translation approved by the Free Software Foundation instead of in the original English. File: lispref.info, Node: Creating Frames, Next: Frame Parameters, Up: Frames Creating Frames =============== To create a new frame, call the function `make-frame'. - Function: make-frame &optional ALIST DEVICE This function creates a new frame on DEVICE, if DEVICE permits creation of frames. (An X server does; an ordinary terminal does not.) DEVICE defaults to the selected device if omitted. *Note Devices::. The argument is an alist specifying frame parameters. Any parameters not mentioned in ALIST default according to the value of the variable `default-frame-alist'. For X devices, parameters not specified in `default-frame-alist' default in turn from `default-x-frame-alist' and, if not specified there, from the X resources. For TTY devices, `default-tty-frame-alist' is consulted as well as `default-frame-alist'. The set of possible parameters depends in principle on what kind of window system XEmacs uses to display its frames. *Note X Frame Parameters::, for documentation of individual parameters you can specify when creating an X window frame. File: lispref.info, Node: Frame Parameters, Next: Frame Titles, Prev: Creating Frames, Up: Frames Frame Parameters ================ A frame has many parameters that control its appearance and behavior. Just what parameters a frame has depends on what display mechanism it uses. Frame parameters exist for the sake of window systems. A terminal frame has a few parameters, mostly for compatibility's sake; only the height, width and `buffer-predicate' parameters really do something. * Menu: * Parameter Access:: How to change a frame's parameters. * Initial Parameters:: Specifying frame parameters when you make a frame. * X Frame Parameters:: List of frame parameters. * Size and Position:: Changing the size and position of a frame. * Frame Name:: The name of a frame (as opposed to its title). File: lispref.info, Node: Parameter Access, Next: Initial Parameters, Up: Frame Parameters Access to Frame Parameters -------------------------- These functions let you read and change the parameter values of a frame. - Function: frame-parameters FRAME The function `frame-parameters' returns an alist listing all the parameters of FRAME and their values. - Function: modify-frame-parameters FRAME ALIST This function alters the parameters of frame FRAME based on the elements of ALIST. Each element of ALIST has the form `(PARM . VALUE)', where PARM is a symbol naming a parameter. If you don't mention a parameter in ALIST, its value doesn't change. File: lispref.info, Node: Initial Parameters, Next: X Frame Parameters, Prev: Parameter Access, Up: Frame Parameters Initial Frame Parameters ------------------------ You can specify the parameters for the initial startup frame by setting `initial-frame-alist' in your `.emacs' file. - Variable: initial-frame-alist This variable's value is an alist of parameter values used when creating the initial X window frame. Each element has the form: (PARAMETER . VALUE) Emacs creates the initial frame before it reads your `~/.emacs' file. After reading that file, Emacs checks `initial-frame-alist', and applies the parameter settings in the altered value to the already created initial frame. If these settings affect the frame geometry and appearance, you'll see the frame appear with the wrong ones and then change to the specified ones. If that bothers you, you can specify the same geometry and appearance with X resources; those do take affect before the frame is created. *Note X Resources: (emacs)Resources X. X resource settings typically apply to all frames. If you want to specify some X resources solely for the sake of the initial frame, and you don't want them to apply to subsequent frames, here's how to achieve this. Specify parameters in `default-frame-alist' to override the X resources for subsequent frames; then, to prevent these from affecting the initial frame, specify the same parameters in `initial-frame-alist' with values that match the X resources. - Variable: default-frame-alist This is an alist specifying default values of frame parameters for subsequent Emacs frames (not the initial ones). See also `special-display-frame-alist', in *Note Choosing Window::. If you use options that specify window appearance when you invoke Emacs, they take effect by adding elements to `default-frame-alist'. One exception is `-geometry', which adds the specified position to `initial-frame-alist' instead. *Note Command Arguments: (emacs)Command Arguments. File: lispref.info, Node: X Frame Parameters, Next: Size and Position, Prev: Initial Parameters, Up: Frame Parameters X Window Frame Parameters ------------------------- Just what parameters a frame has depends on what display mechanism it uses. Here is a table of the parameters of an X window frame; of these, `name', `height', `width', and `buffer-predicate' provide meaningful information in non-X frames. `name' The name of the frame. Most window managers display the frame's name in the frame's border, at the top of the frame. If you don't specify a name, and you have more than one frame, Emacs sets the frame name based on the buffer displayed in the frame's selected window. If you specify the frame name explicitly when you create the frame, the name is also used (instead of the name of the Emacs executable) when looking up X resources for the frame. `display' The display on which to open this frame. It should be a string of the form `"HOST:DPY.SCREEN"', just like the `DISPLAY' environment variable. `left' The screen position of the left edge, in pixels, with respect to the left edge of the screen. The value may be a positive number POS, or a list of the form `(+ POS)' which permits specifying a negative POS value. A negative number -POS, or a list of the form `(- POS)', actually specifies the position of the right edge of the window with respect to the right edge of the screen. A positive value of POS counts toward the left. If the parameter is a negative integer -POS then POS is positive! `top' The screen position of the top edge, in pixels, with respect to the top edge of the screen. The value may be a positive number POS, or a list of the form `(+ POS)' which permits specifying a negative POS value. A negative number -POS, or a list of the form `(- POS)', actually specifies the position of the bottom edge of the window with respect to the bottom edge of the screen. A positive value of POS counts toward the top. If the parameter is a negative integer -POS then POS is positive! `icon-left' The screen position of the left edge *of the frame's icon*, in pixels, counting from the left edge of the screen. This takes effect if and when the frame is iconified. `icon-top' The screen position of the top edge *of the frame's icon*, in pixels, counting from the top edge of the screen. This takes effect if and when the frame is iconified. `user-position' Non-`nil' if the screen position of the frame was explicitly requested by the user (for example, with the `-geometry' option). Nothing automatically makes this parameter non-`nil'; it is up to Lisp programs that call `make-frame' to specify this parameter as well as specifying the `left' and `top' parameters. `height' The height of the frame contents, in characters. (To get the height in pixels, call `frame-pixel-height'; see *Note Size and Position::.) `width' The width of the frame contents, in characters. (To get the height in pixels, call `frame-pixel-width'; see *Note Size and Position::.) `window-id' The number of the X window for the frame. `minibuffer' Whether this frame has its own minibuffer. The value `t' means yes, `nil' means no, `only' means this frame is just a minibuffer. If the value is a minibuffer window (in some other frame), the new frame uses that minibuffer. (Minibuffer-only and minibuffer-less frames are not yet implemented in XEmacs.) `scroll-bar-width' The width of the vertical scroll bar, in pixels. `cursor-color' The color for the cursor that shows point. `border-color' The color for the border of the frame. `border-width' The width in pixels of the window border. `internal-border-width' The distance in pixels between text and border. `unsplittable' If non-`nil', this frame's window is never split automatically. `inter-line-space' The space in pixels between adjacent lines of text. (Not currently implemented.) `modeline' Whether the frame has a modeline. File: lispref.info, Node: Size and Position, Next: Frame Name, Prev: X Frame Parameters, Up: Frame Parameters Frame Size And Position ----------------------- You can read or change the size and position of a frame using the frame parameters `left', `top', `height', and `width'. Whatever geometry parameters you don't specify are chosen by the window manager in its usual fashion. Here are some special features for working with sizes and positions: - Function: set-frame-position FRAME LEFT TOP This function sets the position of the top left corner of FRAME to LEFT and TOP. These arguments are measured in pixels, and count from the top left corner of the screen. Negative parameter values count up or rightward from the top left corner of the screen. - Function: frame-height &optional FRAME - Function: frame-width &optional FRAME These functions return the height and width of FRAME, measured in lines and columns. If you don't supply FRAME, they use the selected frame. - Function: frame-pixel-height &optional FRAME - Function: frame-pixel-width &optional FRAME These functions return the height and width of FRAME, measured in pixels. If you don't supply FRAME, they use the selected frame. - Function: set-frame-size FRAME COLS ROWS &optional PRETEND This function sets the size of FRAME, measured in characters; COLS and ROWS specify the new width and height. (If PRETEND is non-nil, it means that redisplay should act as if the frame's size is COLS by ROWS, but the actual size of the frame should not be changed. You should not normally use this option.) You can also use the functions `set-frame-height' and `set-frame-width' to set the height and width individually. The frame is the first argument and the size (in rows or columns) is the second. (There is an optional third argument, PRETEND, which has the same purpose as the corresponding argument in `set-frame-size'.) File: lispref.info, Node: Frame Name, Prev: Size and Position, Up: Frame Parameters The Name of a Frame (As Opposed to Its Title) --------------------------------------------- Under X, every frame has a name, which is not the same as the title of the frame. A frame's name is used to look up its resources and does not normally change over the lifetime of a frame. It is perfectly allowable, and quite common, for multiple frames to have the same name. - Function: frame-name &optional FRAME This function returns the name of FRAME, which defaults to the selected frame if not specified. The name of a frame can also be obtained from the frame's parameters. *Note Frame Parameters::. - Variable: default-frame-name This variable holds the default name to assign to newly-created frames. This can be overridden by arguments to `make-frame'. This must be a string. File: lispref.info, Node: Frame Titles, Next: Deleting Frames, Prev: Frame Parameters, Up: Frames Frame Titles ============ Every frame has a title; most window managers display the frame title at the top of the frame. You can specify an explicit title with the `name' frame property. But normally you don't specify this explicitly, and Emacs computes the title automatically. Emacs computes the frame title based on a template stored in the variable `frame-title-format'. - Variable: frame-title-format This variable specifies how to compute a title for a frame when you have not explicitly specified one. The variable's value is actually a modeline construct, just like `modeline-format'. *Note Modeline Data::. - Variable: frame-icon-title-format This variable specifies how to compute the title for an iconified frame, when you have not explicitly specified the frame title. This title appears in the icon itself. - Function: x-set-frame-icon-pixmap FRAME PIXMAP &optional MASK This function sets the icon of the given frame to the given image instance, which should be an image instance object (as returned by `make-image-instance'), a glyph object (as returned by `make-glyph'), or `nil'. If a glyph object is given, the glyph will be instantiated on the frame to produce an image instance object. If the given image instance has a mask, that will be used as the icon mask; however, not all window managers support this. The window manager is also not required to support color pixmaps, only bitmaps (one plane deep). If the image instance does not have a mask, then the optional third argument may be the image instance to use as the mask (it must be one plane deep). *Note Glyphs::. File: lispref.info, Node: Deleting Frames, Next: Finding All Frames, Prev: Frame Titles, Up: Frames Deleting Frames =============== Frames remain potentially visible until you explicitly "delete" them. A deleted frame cannot appear on the screen, but continues to exist as a Lisp object until there are no references to it. - Command: delete-frame &optional FRAME This function deletes the frame FRAME. By default, FRAME is the selected frame. - Function: frame-live-p FRAME The function `frame-live-p' returns non-`nil' if the frame FRAME has not been deleted. File: lispref.info, Node: Finding All Frames, Next: Frames and Windows, Prev: Deleting Frames, Up: Frames Finding All Frames ================== - Function: frame-list The function `frame-list' returns a list of all the frames that have not been deleted. It is analogous to `buffer-list' for buffers. The list that you get is newly created, so modifying the list doesn't have any effect on the internals of XEmacs. - Function: device-frame-list &optional DEVICE This function returns a list of all frames on DEVICE. If DEVICE is `nil', the selected device will be used. - Function: visible-frame-list &optional DEVICE This function returns a list of just the currently visible frames. If DEVICE is specified only frames on that device will be returned. *Note Visibility of Frames::. (TTY frames always count as "visible", even though only the selected one is actually displayed.) - Function: next-frame &optional FRAME MINIBUF The function `next-frame' lets you cycle conveniently through all the frames from an arbitrary starting point. It returns the "next" frame after FRAME in the cycle. If FRAME is omitted or `nil', it defaults to the selected frame. The second argument, MINIBUF, says which frames to consider: `nil' Exclude minibuffer-only frames. `visible' Consider all visible frames. 0 Consider all visible or iconified frames. a window Consider only the frames using that particular window as their minibuffer. the symbol `visible' Include all visible frames. `0' Include all visible and iconified frames. anything else Consider all frames. - Function: previous-frame &optional FRAME MINIBUF Like `next-frame', but cycles through all frames in the opposite direction. See also `next-window' and `previous-window', in *Note Cyclic Window Ordering::. File: lispref.info, Node: Frames and Windows, Next: Minibuffers and Frames, Prev: Finding All Frames, Up: Frames Frames and Windows ================== Each window is part of one and only one frame; you can get the frame with `window-frame'. - Function: frame-root-window &optional FRAME This returns the root window of frame FRAME. FRAME defaults to the selected frame if not specified. - Function: window-frame &optional WINDOW This function returns the frame that WINDOW is on. WINDOW defaults to the selected window if omitted. All the non-minibuffer windows in a frame are arranged in a cyclic order. The order runs from the frame's top window, which is at the upper left corner, down and to the right, until it reaches the window at the lower right corner (always the minibuffer window, if the frame has one), and then it moves back to the top. - Function: frame-top-window FRAME This returns the topmost, leftmost window of frame FRAME. At any time, exactly one window on any frame is "selected within the frame". The significance of this designation is that selecting the frame also selects this window. You can get the frame's current selected window with `frame-selected-window'. - Function: frame-selected-window &optional FRAME This function returns the window on FRAME that is selected within FRAME. FRAME defaults to the selected frame if not specified. Conversely, selecting a window for XEmacs with `select-window' also makes that window selected within its frame. *Note Selecting Windows::. Another function that (usually) returns one of the windows in a frame is `minibuffer-window'. *Note Minibuffer Misc::. File: lispref.info, Node: Minibuffers and Frames, Next: Input Focus, Prev: Frames and Windows, Up: Frames Minibuffers and Frames ====================== Normally, each frame has its own minibuffer window at the bottom, which is used whenever that frame is selected. If the frame has a minibuffer, you can get it with `minibuffer-window' (*note Minibuffer Misc::.). However, you can also create a frame with no minibuffer (this is not implemented as of 19.13, but will be in 19.14). Such a frame must use the minibuffer window of some other frame. When you create the frame, you can specify explicitly the minibuffer window to use (in some other frame). If you don't, then the minibuffer is found in the frame which is the value of the variable `default-minibuffer-frame'. Its value should be a frame which does have a minibuffer. - Variable: default-minibuffer-frame This variable specifies the frame to use for the minibuffer window, by default. File: lispref.info, Node: Input Focus, Next: Visibility of Frames, Prev: Minibuffers and Frames, Up: Frames Input Focus =========== At any time, one frame in XEmacs is the "selected frame". The selected window always resides on the selected frame. As the focus moves from device to device, the selected frame on each device is remembered and restored when the focus moves back to that device. - Function: selected-frame &optional DEVICE This function returns the selected frame on DEVICE. If DEVICE is not specified, the selected device will be used. If no frames exist on the device, `nil' is returned. The X server normally directs keyboard input to the X window that the mouse is in. Some window managers use mouse clicks or keyboard events to "shift the focus" to various X windows, overriding the normal behavior of the server. Lisp programs can switch frames "temporarily" by calling the function `select-frame'. This does not override the window manager; rather, it escapes from the window manager's control until that control is somehow reasserted. When using a text-only terminal, there is no window manager; therefore, `select-frame' is the only way to switch frames, and the effect lasts until overridden by a subsequent call to `select-frame'. Only the selected terminal frame is actually displayed on the terminal. Each terminal screen except for the initial one has a number, and the number of the selected frame appears in the mode line after the word `Emacs' (*note Modeline Variables::.). - Function: select-frame FRAME This function selects frame FRAME, temporarily disregarding the focus of the X server if any. The selection of FRAME lasts until the next time the user does something to select a different frame, or until the next time this function is called. Note that this does not actually cause the window-system focus to be set to this frame, or the `select-frame-hook' or `deselect-frame-hook' to be run, until the next time that XEmacs is waiting for an event. File: lispref.info, Node: Visibility of Frames, Next: Raising and Lowering, Prev: Input Focus, Up: Frames Visibility of Frames ==================== An X window frame may be "visible", "invisible", or "iconified". If it is visible, you can see its contents. If it is iconified, the frame's contents do not appear on the screen, but an icon does. If the frame is invisible, it doesn't show on the screen, not even as an icon. Visibility is meaningless for TTY frames, since only the selected one is actually displayed in any case. - Command: make-frame-visible &optional FRAME This function makes frame FRAME visible. If you omit FRAME, it makes the selected frame visible. - Command: make-frame-invisible &optional FRAME This function makes frame FRAME invisible. - Command: iconify-frame &optional FRAME This function iconifies frame FRAME. - Command: deiconify-frame &optional FRAME This function de-iconifies frame FRAME. Under X, this is equivalent to `make-frame-visible'. - Function: frame-visible-p FRAME This returns whether FRAME is currently "visible" (actually in use for display). A frame that is not visible is not updated, and, if it works through a window system, may not show at all. - Function: frame-iconified-p FRAME This returns whether FRAME is iconified. Not all window managers use icons; some merely unmap the window, so this function is not the inverse of `frame-visible-p'. It is possible for a frame to not be visible and not be iconified either. However, if the frame is iconified, it will not be visible. (Under FSF Emacs, the functionality of this function is obtained through `frame-visible-p'.) - Function: frame-totally-visible-p FRAME This returns whether FRAME is not obscured by any other X windows. This function always returns `y' on TTY frames. File: lispref.info, Node: Raising and Lowering, Next: Frame Hooks, Prev: Visibility of Frames, Up: Frames Raising and Lowering Frames =========================== The X Window System uses a desktop metaphor. Part of this metaphor is the idea that windows are stacked in a notional third dimension perpendicular to the screen surface, and thus ordered from "highest" to "lowest". Where two windows overlap, the one higher up covers the one underneath. Even a window at the bottom of the stack can be seen if no other window overlaps it. A window's place in this ordering is not fixed; in fact, users tend to change the order frequently. "Raising" a window means moving it "up", to the top of the stack. "Lowering" a window means moving it to the bottom of the stack. This motion is in the notional third dimension only, and does not change the position of the window on the screen. You can raise and lower XEmacs's X windows with these functions: - Command: raise-frame &optional FRAME This function raises frame FRAME. - Command: lower-frame &optional FRAME This function lowers frame FRAME. You can also specify auto-raise (raising automatically when a frame is selected) or auto-lower (lowering automatically when it is deselected). Under X, most ICCCM-compliant window managers will have an option to do this for you, but the following variables are provided in case you're using a broken WM. (Under FSF Emacs, the same functionality is provided through the `auto-raise' and `auto-lower' frame parameters.) - Variable: auto-raise-frame This variable's value is `t' if frames will be raised to the top when selected. - Variable: auto-lower-frame This variable's value is `t' if frames will be lowered to the bottom when no longer selected. Auto-raising and auto-lowering is implemented through functions attached to `select-frame-hook' and `deselect-frame-hook' (*note Frame Hooks::.). Under normal circumstances, you should not call these functions directly. - Function: default-select-frame-hook This hook function implements the `auto-raise-frame' variable; it is for use as the value of `select-frame-hook'. - Function: default-deselect-frame-hook This hook function implements the `auto-lower-frame' variable; it is for use as the value of `deselect-frame-hook'. File: lispref.info, Node: Frame Hooks, Prev: Raising and Lowering, Up: Frames Hooks for Customizing Frame Behavior ==================================== XEmacs provides many hooks that are called at various times during a frame's lifetime. *Note Hooks::. - Variable: create-frame-hook This hook is called each time a frame is created. The functions are called with one argument, the newly-created frame. - Variable: delete-frame-hook This hook is called each time a frame is deleted. The functions are called with one argument, the about-to-be-deleted frame. - Variable: select-frame-hook This is a normal hook that is run just after a frame is selected. The function `default-select-frame-hook', which implements auto-raising (*note Raising and Lowering::.), is normally attached to this hook. Note that calling `select-frame' does not necessarily set the focus: The actual window-system focus will not be changed until the next time that XEmacs is waiting for an event, and even then, the window manager may refuse the focus-change request. - Variable: deselect-frame-hook This is a normal hook that is run just before a frame is deselected (and another frame is selected). The function `default-deselect-frame-hook', which implements auto-lowering (*note Raising and Lowering::.), is normally attached to this hook. - Variable: map-frame-hook This hook is called each time a frame is mapped (i.e. made visible). The functions are called with one argument, the newly mapped frame. - Variable: unmap-frame-hook This hook is called each time a frame is unmapped (i.e. made invisible or iconified). The functions are called with one argument, the newly unmapped frame. File: lispref.info, Node: Devices, Next: Positions, Prev: Frames, Up: Top Devices ******* A "device" is an object representing a connection to a particular display device, such as an X display or a tty. Each device has one or more "frames" in which text can be displayed. For X displays and the like, a frame corresponds to the normal window-system concept of a window. Frames can overlap, be displayed at various locations within the display, be resized, etc. For tty's, only one frame can be displayed at a time, and it occupies the entire tty display area. However, you can still define multiple frames and switch between them. Their contents are entirely separate from each other. These sorts of frames resemble the "virtual console" capability provided under Linux or the multiple screens provided by the multiplexing program `screen' under Unix. When you start up XEmacs, an initial device is created to display frames on. This will either be an X device or a tty device, depending on what mode you started XEmacs in (this is determined by the `DISPLAY' environment variable, the `-nw', `-t' and `-display' command-line options, etc.). You can connect to other devices by creating device objects, as described below. Many functions (for example the frame-creation functions) take an optional device argument specifying which device the function pertains to. If the argument is omitted, it defaults to the selected device (see below). - Function: devicep OBJECT This returns non-`nil' if OBJECT is a device. * Menu: * Basic Device Functions:: * Device Types and Classes:: * Connecting to a Device:: * The Selected Device:: * Device Input:: File: lispref.info, Node: Basic Device Functions, Next: Device Types and Classes, Up: Devices Basic Device Functions ====================== - Function: device-list This function returns a list of all existing devices. - Function: device-or-frame-p OBJECT This function returns non-`nil' if OBJECT is a device or frame. This function is useful because devices and frames are similar in many respects and many functions can operate on either one. - Function: device-frame-list DEVICE This function returns a list of all frames on DEVICE. - Function: frame-device FRAME This function returns the device that FRAME is on. File: lispref.info, Node: Device Types and Classes, Next: Connecting to a Device, Prev: Basic Device Functions, Up: Devices Device Types and Classes ======================== Every device is of a particular "type", which describes how the connection to that device is made and how the device operates, and a particular "class", which describes other characteristics of the device (currently, the color capabilities of the device). The currently-defined device types are `x' A connection to an X display (such as `willow:0'). `tty' A connection to a tty (such as `/dev/ttyp3'). `terminal' A stdio connection. This describes a device for which input and output is only possible in a stream-like fashion, such as when XEmacs in running in batch mode. The very first device created by XEmacs is a terminal device and is used to print out messages of various sorts (for example, the help message when you use the `-help' command-line option). The currently-defined device classes are `color' A color device. `grayscale' A grayscale device (a device that can display multiple shades of gray, but no color). `mono' A device that can only display two colors (e.g. black and white). - Function: device-type DEVICE This function returns the type of DEVICE. This is a symbol whose name is one of the device types mentioned above. - Function: device-or-frame-type DEVICE-OR-FRAME This function returns the type of DEVICE-OR-FRAME. - Function: device-class DEVICE This function returns the class (color behavior) of DEVICE. This is a symbol whose name is one of the device classes mentioned above. - Function: valid-device-type DEVICE-TYPE This function returns whether DEVICE-TYPE (which should be a symbol) species a valid device type. - Function: valid-device-class DEVICE-CLASS This function returns whether DEVICE-CLASS (which should be a symbol) species a valid device class. - Variable: terminal-device This variable holds the initial terminal device object, which represents XEmacs's stdout. File: lispref.info, Node: Connecting to a Device, Next: The Selected Device, Prev: Device Types and Classes, Up: Devices Connecting to a Device ====================== - Function: make-device &optional TYPE DEVICE-DATA This function creates a new device. The following two functions create devices of specific types and are written in terms of `make-device'. - Function: make-tty-device &optional TTY TERMINAL-TYPE This function creates a new tty device on TTY. This also creates the tty's first frame. TTY should be a string giving the name of a tty device file (e.g. `/dev/ttyp3' under SunOS et al.), as returned by the `tty' command issued from the Unix shell. A value of `nil' means use the stdin and stdout as passed to XEmacs from the shell. If TERMINAL-TYPE is non-`nil', it should be a string specifying the type of the terminal attached to the specified tty. If it is `nil', the terminal type will be inferred from the `TERM' environment variable. - Function: make-x-device &optional DISPLAY ARGV-LIST This function creates a new device connected to DISPLAY. Optional argument ARGV-LIST is a list of strings describing command line options. - Function: delete-device DEVICE This function deletes DEVICE, permanently eliminating it from use. This disconnects XEmacs's connection to the device. - Variable: create-device-hook This variable, if non-`nil', should contain a list of functions, which are called when a device is created. - Variable: delete-device-hook This variable, if non-`nil', should contain a list of functions, which are called when a device is deleted. - Function: device-live-p OBJECT This function returns non-`nil' if OBJECT is a device that has not been deleted. - Function: device-x-display DEVICE This function returns the X display which DEVICE is connected to, if DEVICE is an X device. File: lispref.info, Node: The Selected Device, Next: Device Input, Prev: Connecting to a Device, Up: Devices The Selected Device =================== - Function: select-device DEVICE This function selects the device DEVICE. - Function: selected-device This function returns the device which is currently active. File: lispref.info, Node: Device Input, Prev: The Selected Device, Up: Devices Device Input ============ - Function: device-baud-rate DEVICE This function returns the output baud rate of DEVICE. - Function: device-disable-input DEVICE This function disables input on device DEVICE. - Function: device-enable-input DEVICE This function enables input on device DEVICE. - Function: device-function-keymap DEVICE This function returns the function key mapping for DEVICE. - Function: set-device-baud-rate DEVICE RATE This function sets the output baud rate of DEVICE to RATE. - Function: set-device-function-keymap DEVICE KEYMAP This function sets the function mapping for DEVICE to KEYMAP. File: lispref.info, Node: Positions, Next: Markers, Prev: Devices, Up: Top Positions ********* A "position" is the index of a character in the text of a buffer. More precisely, a position identifies the place between two characters (or before the first character, or after the last character), so we can speak of the character before or after a given position. However, we often speak of the character "at" a position, meaning the character after that position. Positions are usually represented as integers starting from 1, but can also be represented as "markers"--special objects that relocate automatically when text is inserted or deleted so they stay with the surrounding characters. *Note Markers::. * Menu: * Point:: The special position where editing takes place. * Motion:: Changing point. * Excursions:: Temporary motion and buffer changes. * Narrowing:: Restricting editing to a portion of the buffer. File: lispref.info, Node: Point, Next: Motion, Up: Positions Point ===== "Point" is a special buffer position used by many editing commands, including the self-inserting typed characters and text insertion functions. Other commands move point through the text to allow editing and insertion at different places. Like other positions, point designates a place between two characters (or before the first character, or after the last character), rather than a particular character. Usually terminals display the cursor over the character that immediately follows point; point is actually before the character on which the cursor sits. The value of point is a number between 1 and the buffer size plus 1. If narrowing is in effect (*note Narrowing::.), then point is constrained to fall within the accessible portion of the buffer (possibly at one end of it). Each buffer has its own value of point, which is independent of the value of point in other buffers. Each window also has a value of point, which is independent of the value of point in other windows on the same buffer. This is why point can have different values in various windows that display the same buffer. When a buffer appears in only one window, the buffer's point and the window's point normally have the same value, so the distinction is rarely important. *Note Window Point::, for more details. - Function: point This function returns the value of point in the current buffer, as an integer. (point) => 175 - Function: point-min This function returns the minimum accessible value of point in the current buffer. This is normally 1, but if narrowing is in effect, it is the position of the start of the region that you narrowed to. (*Note Narrowing::.) - Function: point-max This function returns the maximum accessible value of point in the current buffer. This is `(1+ (buffer-size))', unless narrowing is in effect, in which case it is the position of the end of the region that you narrowed to. (*Note Narrowing::). - Function: buffer-end FLAG This function returns `(point-min)' if FLAG is less than 1, `(point-max)' otherwise. The argument FLAG must be a number. - Function: buffer-size This function returns the total number of characters in the current buffer. In the absence of any narrowing (*note Narrowing::.), `point-max' returns a value one larger than this. (buffer-size) => 35 (point-max) => 36 - Variable: buffer-saved-size The value of this buffer-local variable is the former length of the current buffer, as of the last time it was read in, saved or auto-saved. File: lispref.info, Node: Motion, Next: Excursions, Prev: Point, Up: Positions Motion ====== Motion functions change the value of point, either relative to the current value of point, relative to the beginning or end of the buffer, or relative to the edges of the selected window. *Note Point::. * Menu: * Character Motion:: Moving in terms of characters. * Word Motion:: Moving in terms of words. * Buffer End Motion:: Moving to the beginning or end of the buffer. * Text Lines:: Moving in terms of lines of text. * Screen Lines:: Moving in terms of lines as displayed. * List Motion:: Moving by parsing lists and sexps. * Skipping Characters:: Skipping characters belonging to a certain set. File: lispref.info, Node: Character Motion, Next: Word Motion, Up: Motion Motion by Characters -------------------- These functions move point based on a count of characters. `goto-char' is the fundamental primitive; the other functions use that. - Command: goto-char POSITION This function sets point in the current buffer to the value POSITION. If POSITION is less than 1, it moves point to the beginning of the buffer. If POSITION is greater than the length of the buffer, it moves point to the end. If narrowing is in effect, POSITION still counts from the beginning of the buffer, but point cannot go outside the accessible portion. If POSITION is out of range, `goto-char' moves point to the beginning or the end of the accessible portion. When this function is called interactively, POSITION is the numeric prefix argument, if provided; otherwise it is read from the minibuffer. `goto-char' returns POSITION. - Command: forward-char &optional COUNT This function moves point COUNT characters forward, towards the end of the buffer (or backward, towards the beginning of the buffer, if COUNT is negative). If the function attempts to move point past the beginning or end of the buffer (or the limits of the accessible portion, when narrowing is in effect), an error is signaled with error code `beginning-of-buffer' or `end-of-buffer'. In an interactive call, COUNT is the numeric prefix argument. - Command: backward-char &optional COUNT This function moves point COUNT characters backward, towards the beginning of the buffer (or forward, towards the end of the buffer, if COUNT is negative). If the function attempts to move point past the beginning or end of the buffer (or the limits of the accessible portion, when narrowing is in effect), an error is signaled with error code `beginning-of-buffer' or `end-of-buffer'. In an interactive call, COUNT is the numeric prefix argument. File: lispref.info, Node: Word Motion, Next: Buffer End Motion, Prev: Character Motion, Up: Motion Motion by Words --------------- These functions for parsing words use the syntax table to decide whether a given character is part of a word. *Note Syntax Tables::. - Command: forward-word COUNT This function moves point forward COUNT words (or backward if COUNT is negative). Normally it returns `t'. If this motion encounters the beginning or end of the buffer, or the limits of the accessible portion when narrowing is in effect, point stops there and the value is `nil'. In an interactive call, COUNT is set to the numeric prefix argument. - Command: backward-word COUNT This function is just like `forward-word', except that it moves backward until encountering the front of a word, rather than forward. In an interactive call, COUNT is set to the numeric prefix argument. This function is rarely used in programs, as it is more efficient to call `forward-word' with a negative argument. - Variable: words-include-escapes This variable affects the behavior of `forward-word' and everything that uses it. If it is non-`nil', then characters in the "escape" and "character quote" syntax classes count as part of words. Otherwise, they do not. File: lispref.info, Node: Buffer End Motion, Next: Text Lines, Prev: Word Motion, Up: Motion Motion to an End of the Buffer ------------------------------ To move point to the beginning of the buffer, write: (goto-char (point-min)) Likewise, to move to the end of the buffer, use: (goto-char (point-max)) Here are two commands that users use to do these things. They are documented here to warn you not to use them in Lisp programs, because they set the mark and display messages in the echo area. - Command: beginning-of-buffer &optional N This function moves point to the beginning of the buffer (or the limits of the accessible portion, when narrowing is in effect), setting the mark at the previous position. If N is non-`nil', then it puts point N tenths of the way from the beginning of the buffer. In an interactive call, N is the numeric prefix argument, if provided; otherwise N defaults to `nil'. Don't use this function in Lisp programs! - Command: end-of-buffer &optional N This function moves point to the end of the buffer (or the limits of the accessible portion, when narrowing is in effect), setting the mark at the previous position. If N is non-`nil', then it puts point N tenths of the way from the end of the buffer. In an interactive call, N is the numeric prefix argument, if provided; otherwise N defaults to `nil'. Don't use this function in Lisp programs! File: lispref.info, Node: Text Lines, Next: Screen Lines, Prev: Buffer End Motion, Up: Motion Motion by Text Lines -------------------- Text lines are portions of the buffer delimited by newline characters, which are regarded as part of the previous line. The first text line begins at the beginning of the buffer, and the last text line ends at the end of the buffer whether or not the last character is a newline. The division of the buffer into text lines is not affected by the width of the window, by line continuation in display, or by how tabs and control characters are displayed. - Command: goto-line LINE This function moves point to the front of the LINEth line, counting from line 1 at beginning of the buffer. If LINE is less than 1, it moves point to the beginning of the buffer. If LINE is greater than the number of lines in the buffer, it moves point to the end of the buffer--that is, the *end of the last line* of the buffer. This is the only case in which `goto-line' does not necessarily move to the beginning of a line. If narrowing is in effect, then LINE still counts from the beginning of the buffer, but point cannot go outside the accessible portion. So `goto-line' moves point to the beginning or end of the accessible portion, if the line number specifies an inaccessible position. The return value of `goto-line' is the difference between LINE and the line number of the line to which point actually was able to move (in the full buffer, before taking account of narrowing). Thus, the value is positive if the scan encounters the real end of the buffer. The value is zero if scan encounters the end of the accessible portion but not the real end of the buffer. In an interactive call, LINE is the numeric prefix argument if one has been provided. Otherwise LINE is read in the minibuffer. - Command: beginning-of-line &optional COUNT This function moves point to the beginning of the current line. With an argument COUNT not `nil' or 1, it moves forward COUNT-1 lines and then to the beginning of the line. If this function reaches the end of the buffer (or of the accessible portion, if narrowing is in effect), it positions point there. No error is signaled. - Command: end-of-line &optional COUNT This function moves point to the end of the current line. With an argument COUNT not `nil' or 1, it moves forward COUNT-1 lines and then to the end of the line. If this function reaches the end of the buffer (or of the accessible portion, if narrowing is in effect), it positions point there. No error is signaled. - Command: forward-line &optional COUNT This function moves point forward COUNT lines, to the beginning of the line. If COUNT is negative, it moves point -COUNT lines backward, to the beginning of a line. If COUNT is zero, it moves point to the beginning of the current line. If `forward-line' encounters the beginning or end of the buffer (or of the accessible portion) before finding that many lines, it sets point there. No error is signaled. `forward-line' returns the difference between COUNT and the number of lines actually moved. If you attempt to move down five lines from the beginning of a buffer that has only three lines, point stops at the end of the last line, and the value will be 2. In an interactive call, COUNT is the numeric prefix argument. - Function: count-lines START END This function returns the number of lines between the positions START and END in the current buffer. If START and END are equal, then it returns 0. Otherwise it returns at least 1, even if START and END are on the same line. This is because the text between them, considered in isolation, must contain at least one line unless it is empty. Here is an example of using `count-lines': (defun current-line () "Return the vertical position of point..." (+ (count-lines (window-start) (point)) (if (= (current-column) 0) 1 0) -1)) Also see the functions `bolp' and `eolp' in *Note Near Point::. These functions do not move point, but test whether it is already at the beginning or end of a line.